feat(webapp): hosted webhook ingress, delivery pipeline, and dashboard - #4344

packages/cli-v3/src/dev/devSupervisor.ts-476-476 (1)

476-476: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Fail dequeued runs whose worker is unavailable.

Removing #failRunWithMissingWorker leaves this attempt without a controller or terminal API update. It can remain stuck or be repeatedly redelivered. Restore the terminal failure call before continuing.

.changeset/hosted-webhook-ingress.md-8-14 (1)

8-14: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Do not publish this as generally available while the feature flag remains disabled.

The PR objective says hosted webhooks are unreleased and disabled by default, but these changes publish a release and public documentation that present it as available.

• .changeset/hosted-webhook-ingress.md#L8-L14: defer the public release until rollout, or use the project’s preview-release mechanism.
• docs/docs.json#L164-L176: keep the navigation out of public docs until the feature is enabled.
• docs/webhooks/overview.mdx#L7-L9: clearly mark and gate the feature as preview if these docs must ship first.

internal-packages/clickhouse/src/webhookDeliveries.ts-140-154 (1)

140-154: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Exclude tombstoned deliveries from grouped counts.

count(DISTINCT delivery_id) deduplicates status versions but still counts a delivery whose latest row has _is_deleted = 1. Unlike the list and total-count builders, this query skips FINAL, so endpoint totals can be stale after deletes. Use FINAL or a version-aware argMax aggregation.

Proposed fix

-      "SELECT webhook_endpoint_id, count(DISTINCT delivery_id) AS count FROM trigger_dev.webhook_deliveries_v1",
+      "SELECT webhook_endpoint_id, count() AS count FROM trigger_dev.webhook_deliveries_v1 FINAL",

internal-packages/replication/src/client.ts-450-462 (1)

450-462: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Validate existing publications against publish_via_partition_root.

#validatePublicationConfiguration() checks the publication table and actions, but not pg_publication.pubviaroot. A partitioned source publication created without pubviaroot = true will be reused, so replication will stream events using child-partition identity/schema instead of the intended root-table semantics. Compare pubviaroot when publishViaPartitionRoot is enabled and fail with remediation guidance such as ALTER PUBLICATION ... SET (publish_via_partition_root = true).

internal-packages/webhook-sources/src/index.ts-22-27 (1)

22-27: 🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Make individual samples uniquely addressable.

getSample() returns the first duplicate (provider, eventType). Selecting “Inbound image message” returns the text-message body; Zendesk’s later ticket.updated examples are similarly unreachable. Add a stable sample ID to manifest items and use it for lookup.

Based on supplied context, apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.webhooks.samples.ts:53-57 calls this function with only provider and event type.

internal-packages/webhook-sources/catalog/providers.json-1-1 (1)

1-1: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Catalog checklist contradicts the registry files' own "sample-only" doc comments for workos and zendesk.

Both providers.json entries claim roundTrip/producer are done and tier first-class, but the corresponding registry files explicitly state, in the present tense, that the provider currently ships sample-only pending a custom verifier config — the opposite conclusion. Compare with anthropic/hubspot/twilio in the same file, which correctly downgraded tier and checklist when a similar caveat applied.

• internal-packages/webhook-sources/catalog/providers.json#L903-923: either downgrade the workos entry to tier: "sample-only" with only registryEntry/samples checked, or confirm a custom verifier + round-trip test genuinely exists and update registry/workos.ts's stale comment.
• internal-packages/webhook-sources/catalog/providers.json#L660-681: same reconciliation needed for the zendesk entry.
• internal-packages/webhook-sources/src/registry/workos.ts#L4-6: if the checklist is correct, update this comment — it currently reads as if verification is still pending.
• internal-packages/webhook-sources/src/registry/zendesk.ts#L4-8: same — update this comment if verification is in fact complete.

internal-packages/webhook-sources/src/handAuthored/sentry.ts-58-60 (1)

58-60: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Keep Sentry-Hook-Resource resource-level.

All four samples set the resource header to <resource>.<action>, but Sentry delivers only the resource in the reserved Sentry-Hook-Resource header (issue or error here), while the action lives in the payload. Update issue.created/resolved/assigned to issue and error.created to error; also apply the same change to internal-packages/webhook-sources/src/handAuthored/sentry.ts:114-116, 174-176, 253-255.

Source: MCP tools

internal-packages/webhook-sources/src/registry/telegram.ts-17-18 (1)

17-18: 🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Do not use the Telegram message object as the event-type path.

Line 17 resolves to an object, not an event-type value, and is absent for most Telegram Update variants. Extend EventTypeSource and its consumer to support top-level-key discrimination, or provide a provider-specific extractor before enabling this entry.

internal-packages/webhook-sources/src/registry/whatsapp.ts-18-18 (1)

18-18: 🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Do not use field as WhatsApp’s event discriminant.

The configured path is "messages" for both inbound messages and status updates, so routing and filtering cannot distinguish them. Use an extractor that checks value.messages versus value.statuses, or extend the source contract to support key-presence discrimination.

apps/webapp/app/db.server.ts-270-278 (1)

270-278: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Unhandled promise rejection risk on client.$connect().

client.$connect() at line 275 is fire-and-forget: no await, no .catch(). This function is now the single construction point for 4 Prisma clients (main writer/reader plus the new webhook writer/reader). If any of DATABASE_URL, DATABASE_READ_REPLICA_URL, WEBHOOK_DATABASE_URL, or WEBHOOK_DATABASE_READ_REPLICA_URL is misconfigured, the rejected connect promise goes unhandled — in modern Node this crashes the process instead of surfacing a clear, logged error. The "connected" console.log right after also prints unconditionally, independent of whether the connection actually succeeded.

🛡️ Proposed fix: observe the connect promise

   // connect eagerly
-  client.$connect();
-
-  console.log(`🔌 ${clientType} prisma client connected`);
+  client
+    .$connect()
+    .then(() => console.log(`🔌 ${clientType} prisma client connected`))
+    .catch((error) => {
+      logger.error(`Failed to connect ${clientType} prisma client`, {
+        clientType,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    });

apps/webapp/app/services/realtime/sessions.server.ts-118-125 (1)

118-125: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Use findFirst instead of findUnique.

findSessionByExternalId queries with findUnique. The composite key works equally with findFirst, which is the required convention in this codebase.

♻️ Proposed change

-  return prisma.session.findUnique({
+  return prisma.session.findFirst({
     where: { runtimeEnvironmentId_externalId: { runtimeEnvironmentId: environment.id, externalId } },
   });

As per path instructions: "Always use Prisma findFirst instead of findUnique."

Source: Path instructions

apps/webapp/app/env.server.ts-1523-1524 (1)

1523-1524: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Default the webhook feature flags to opt-in.

entry.server.tsx touches the webhookEngine singleton at startup, so the worker starts unless its disabled flag is "0". Since WEBHOOK_WORKER_ENABLED defaults from WORKER_ENABLED (?? "true"), existing deploys with WORKER_ENABLED=true will start the webhook redis-worker on upgrade. WEBHOOK_INGRESS_ENABLED also defaults to "1". Hard-default both flags to "0" unless each feature is behind a separate rollout gate.

Source: Learnings

apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.webhooks.deliveries.live.ts-65-77 (1)

65-77: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Auth/scope check is skipped when no filters are supplied.

The empty-result short-circuit (line 73-75) runs before loadProjectEnvironmentFromRequest (line 77), so a request to this route with no deliveryIds/since params never authenticates or validates org/project/env scope — it just returns 200 { deliveries: [] }. Move the check after resolving project/environment so the route consistently enforces auth regardless of which filters are present.

🔒 Proposed fix: authenticate/scope before short-circuiting

   const newDeliveriesSince =
     includeNewDeliveries && since !== undefined ? since : undefined;

-  if (deliveryIds.length === 0 && newDeliveriesSince === undefined) {
-    return typedjson({ deliveries: [] });
-  }
-
   const { project, environment } = await loadProjectEnvironmentFromRequest(request, params);
 
+  if (deliveryIds.length === 0 && newDeliveriesSince === undefined) {
+    return typedjson({ deliveries: [] });
+  }
+
   const clickhouse = await clickhouseFactory.getClickhouseForOrganization(

apps/webapp/app/v3/services/createDeploymentBackgroundWorkerV4.server.ts-230-246 (1)

230-246: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Non-ServiceValidationError webhook sync failures are silently swallowed.

Unlike the schedules block just above (lines 199-228), a transient/unexpected webhooksError that isn't a ServiceValidationError is only logged — the deployment then proceeds to DEPLOYING as if webhook sync succeeded, leaving WebhookEndpoint rows stale/missing. createDeploymentBackgroundWorkerV3.server.ts doesn't have this gap since its surrounding try/catch fails the deployment on any error.

🐛 Proposed fix: fail the deployment on any webhook sync error

       if (webhooksError) {
         logger.error("Error syncing declarative webhooks", { error: webhooksError });
         if (webhooksError instanceof ServiceValidationError) {
           await this.#failBackgroundWorkerDeployment(deployment, webhooksError);
           throw webhooksError;
         }
+
+        const serviceError = new ServiceValidationError("Error syncing declarative webhooks");
+        await this.#failBackgroundWorkerDeployment(deployment, serviceError);
+        throw serviceError;
       }

apps/webapp/app/routes/api.v1.webhooks.endpoints.$endpointId.disable.ts-26-33 (1)

26-33: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Read-after-write via replica right after a primary write can return stale status.

webhookPrisma.webhookEndpoint.update writes to the primary, but findWebhookEndpointResource reads through ApiWebhookEndpointPresenter, which queries webhookReplica. If replication lags, the API response to this "disable" call can still show the endpoint's old status instead of inactive.

🛡️ Proposed fix

-    await webhookPrisma.webhookEndpoint.update({
+    const updated = await webhookPrisma.webhookEndpoint.update({
       where: { id: endpoint.id },
       data: { status: "INACTIVE" },
     });
     webhookEngine.invalidateEndpoint(endpoint.opaqueId);

-    return json(await findWebhookEndpointResource(authentication, params.endpointId));
+    // Build the response from the primary-write result to avoid replica-lag staleness.
+    return json(toApiEndpointFromPrimary(updated));

Alternatively, have the presenter accept an explicit Prisma client so this route can pass webhookPrisma for a guaranteed-fresh read.

apps/webapp/app/presenters/v3/ApiWebhookDeliveryPresenter.server.ts-92-105 (1)

92-105: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Pagination cursor/direction disagree when both page[after] and page[before] are supplied.

cursor resolves page[after] first, but direction resolves page[before] first. If both are present, the request is sent as direction: "backward" while using the page[after] value as the cursor — an inconsistent pair. Per the established convention, page[before] should win for both the cursor value and the direction.

🐛 Proposed fix

-        cursor: searchParams["page[after]"] ?? searchParams["page[before]"],
+        cursor: searchParams["page[before]"] ?? searchParams["page[after]"],
         direction: searchParams["page[before]"] ? "backward" : "forward",

Based on learnings, "it is an established shared convention to allow both cursor query params page[after] and page[before]... When both are present, page[before] must take precedence (i.e., it should be used/wins)."

Source: Learnings

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.webhooks.deliveries.$deliveryParam/route.tsx-134-175 (1)

134-175: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Fix the hook call order before the early return.

useState is currently reached only after delivery is truthy, so any render transition between the missing-delivery branch and the delivery branch changes the hook order/instance count within the same component instance. Move this hook above the !delivery return.

apps/webapp/app/routes/api.v1.webhooks.endpoints.$endpointId.enable.ts-26-33 (1)

26-33: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Route the response through the primary webhook client.

endpoint.update() is performed with webhookPrisma, but the returned resource is built from findWebhookEndpointResource, whose ApiWebhookEndpointPresenter reads via webhookReplica. Replica lag can return the previous PAUSED status immediately after enabling; build the response from the updated endpoint row or re-fetch via webookPrisma.

apps/webapp/app/routes/api.v1.webhooks.endpoints.$endpointId.rotate-secret.ts-37-47 (1)

37-47: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Secret rotation isn't fail-safe: a mid-request failure can permanently strand the endpoint.

secretKey (Line 38) is deterministic per endpoint, so setSecret (Line 39) overwrites the endpoint's live signing secret immediately — before the caller has received the response at Line 47. Since prisma (secret store) and webhookPrisma (endpoint row) are separate databases, these writes cannot be made atomic with a single $transaction. If the process fails between line 39 and line 47 (network drop, the webhookPrisma.webhookEndpoint.update throwing, etc.), the new secret is already live, the caller never received it, and there is no way to retrieve it again — the endpoint is effectively bricked until another rotation, which carries the same risk.

🔒 Suggested fix: version the key, swap the pointer, don't overwrite in place

-    const secret = `whsec_${randomBytes(32).toString("hex")}`;
-    const secretKey = `webhook:signing-secret:${endpoint.id}`;
-    await getSecretStore("DATABASE", { prismaClient: prisma }).setSecret(secretKey, { secret });
-    await webhookPrisma.webhookEndpoint.update({
-      where: { id: endpoint.id },
-      data: { signingSecretKey: secretKey },
-    });
+    const secret = `whsec_${randomBytes(32).toString("hex")}`;
+    const secretKey = `webhook:signing-secret:${endpoint.id}:${randomBytes(8).toString("hex")}`;
+    await getSecretStore("DATABASE", { prismaClient: prisma }).setSecret(secretKey, { secret });
+    // Only swap the pointer after the new secret is durably stored; the old secret
+    // (and old key) remain valid verification material until this succeeds.
+    await webhookPrisma.webhookEndpoint.update({
+      where: { id: endpoint.id },
+      data: { signingSecretKey: secretKey },
+    });
+    // TODO: schedule deletion of the previous secretKey after a grace period.

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.webhooks._index/route.tsx-116-133 (1)

116-133: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Presenter failures are silently swallowed as "no deliveries."

.catch(() => ({ deliveries: [], pagination: {} })) masks any ClickHouse/DB failure as an empty result with no logging. Users see "No deliveries for this webhook yet" during an actual outage, and there's no signal for on-call to notice the failure.

🩹 Suggested fix

   const list = await presenter
     .call({...})
-    .catch(() => ({ deliveries: [], pagination: {} }));
+    .catch((error) => {
+      logger.error("Failed to load webhook deliveries", { error });
+      return { deliveries: [], pagination: {}, error: true };
+    });

Then surface error in the UI as a distinct state from "no data yet."

internal-packages/webhook-engine/src/engine/filter/parse.ts-173-180 (1)

173-180: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Field-to-field (valueRef) clauses silently always fail for non-comparison operators.

parseOp accepts word operators (in, startsWith, endsWith, contains, and nin via not in), and the branch below then builds a valueRef clause for any of them when the RHS is a namespace-prefixed word. But applyOpRef in evaluate.ts only implements eq/neq/gt/lt/gte/lte and returns false in its default case — so a filter like event.tags in event.allowed or event.title startsWith event.repository.name parses cleanly yet evaluates to false for every delivery. For a routing/loop-guard filter this is a silent no-match that drops all events.

The comment in evaluate.ts ("Non-comparison ops are rejected by the parser/types") documents the intended contract, but nothing enforces it here. Reject non-comparison ops when building a valueRef clause so authors get a FilterParseError instead of a silently-dead filter.

🐛 Proposed guard

     const operand = peek();
     if (operand?.t === "word" && NAMESPACES.has(operand.v.split(".")[0])) {
       next();
+      if (op !== "eq" && op !== "neq" && op !== "gt" && op !== "lt" && op !== "gte" && op !== "lte") {
+        throw new FilterParseError(
+          `field-to-field comparison only supports ==, !=, >, <, >=, <= (got "${op}")`
+        );
+      }
       return { kind: "clause", path, op, valueRef: operand.v };
     }

internal-packages/webhook-engine/src/engine/verification/hmac.ts-33-37 (1)

33-37: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Reject parsing failures before returning ok: true. parseEventBody() and tryParseJson() return { error } for non-parseable bodies, but hmac.ts and sharedSecret.ts spread that result into the success object, producing ok: true with an error field and no parsedEvent. Check .error and return the verifier’s fail(...) path before building the ok: true result; for sharedSecret.ts, this affects the success path on placement: "header"/bearer/basic secrets, and body secrets already fail to extract when parsing fails.

internal-packages/webhook-engine/src/engine/verification/index.ts-21-41 (1)

21-41: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

verify()'s call graph can throw synchronously, breaking the fail-closed contract relied on by the caller. The engine/index.ts ingest() flow explicitly safeParses the artifact and calls verify() with no try/catch, intending that bad input always becomes { outcome: "verification_failed" } (a 400) rather than a 5xx. Two spots inside the verify() call graph currently violate that assumption by throwing raw Errors instead of returning { ok: false }.

• internal-packages/webhook-engine/src/engine/verification/index.ts#L21-L41: return { ok: false, error } instead of throwing for the "bundle" kind and the unregistered-scheme default branch.
• internal-packages/webhook-engine/src/engine/verification/urlSecret.ts#L9-L17: wrap new URL(input.url) in a try/catch and return { ok: false, error: "invalid url", ... } on failure instead of letting it throw.

docs/webhooks/channels.mdx-11-19 (1)

11-19: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Make the examples self-contained.

• docs/webhooks/channels.mdx#L11-L19: import streamText from ai and anthropic from @ai-sdk/anthropic.
• docs/webhooks/human-in-the-loop.mdx#L101-L105: import webhooks from @trigger.dev/sdk.

As per coding guidelines, “Code examples must be complete and runnable where possible.”

Source: Coding guidelines

docs/webhooks/connect.mdx-3-3 (1)

3-3: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Describe this as a verification credential, not always a signing secret.

webhooks.discord() uses the provider’s public key rather than a shared secret, so these universal instructions lead Discord users to configure the wrong value. Distinguish shared-secret and public-key flows.

Also applies to: 15-22

internal-packages/webhook-sources/catalog/mark.ts-33-45 (1)

33-45: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Keep preset, tier, and checklist state consistent.

--preset accepts arbitrary values and does not recompute the tier; --tier sample-only can also retain a preset. Derive tier/checklist from a validated preset, or reject contradictory flag combinations.

internal-packages/webhook-sources/catalog/build-brief.md-24-24 (1)

24-24: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add a language tag to the TypeScript fence.

This triggers MD040.

Proposed fix

-```
+```typescript

Source: Linters/SAST tools

internal-packages/webhook-sources/catalog/build-v1.ts-33-33 (1)

33-33: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Keep Jira out of the github preset.

Jira Cloud uses X-Hub-Signature with sha256=, while the catalog’s github preset models X-Hub-Signature-256; this makes the generated tier/checklist incorrectly first-class and can break round-trip verification. Set this row’s preset to null until a Jira-specific verifier is added.

internal-packages/webhook-sources/catalog/status.ts-7-18 (1)

7-18: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

sampleCount is never populated, so the CLI always reports "no samples yet".

Provider.sampleCount is read at Line 83, but no entry in providers.json sets this field, so p.sampleCount is always undefined and ${samples} always resolves to "no samples yet" regardless of actual sample coverage — the reported status is misleading for every provider.

🐛 Proposed fix: derive sampleCount instead of trusting an unset JSON field

-const line = (p: Provider) => {
+const line = (p: Provider, sampleCounts: Record<string, number>) => {
   const { done, total } = dodProgress(p);
   const owner = p.owner ? ` owner=${p.owner}` : "";
   const drift = p.status === "complete" && !derivedComplete(p) ? "  [!] checklist incomplete" : "";
-  const samples = p.sampleCount > 0 ? `${p.sampleCount} samples` : "no samples yet";
+  const count = sampleCounts[p.id] ?? 0;
+  const samples = count > 0 ? `${count} samples` : "no samples yet";

Do you want me to wire in an actual sample count (e.g. by importing/counting `src/samples.ts` entries per provider)?

Also applies to: 79-87

internal-packages/webhook-sources/src/registry/postmark.ts-3-17 (1)

3-17: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Point docsUrl at Postmark’s general webhook page.

This registry entry models Postmark delivery-related webhooks with RecordType, but the docsUrl sends users to the separate inbound-webhook documentation. Use the webhook overview URL so the docs match the configured event type.

Suggested fix

-  docsUrl: "https://postmarkapp.com/developer/webhooks/inbound-webhook",
+  docsUrl: "https://postmarkapp.com/developer/webhooks/webhooks-overview",

internal-packages/webhook-sources/src/handAuthored/vapi.ts-20-29 (1)

20-29: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Align epoch timestamps with the ISO timestamps.

The timestamp and artifact message times resolve to July 8, 2026, while the same call’s createdAt and updatedAt are July 14, 2026. Regenerate the epoch-millisecond values from the July 14 timestamps so the sample is internally coherent.

Also applies to: 113-121, 127-147

internal-packages/webhook-sources/src/handAuthored/brex.ts-7-10 (1)

7-10: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Fix the extrapolated USER_UPDATED sample shape.

USER_UPDATED should include the required Brex fields: event_type, user_id, company_id, and updated_attributes. The current sample hides required payload structure and can mislead users building filters or payloads.

internal-packages/webhook-sources/src/handAuthored/openai.ts-19-19 (1)

19-19: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Use a distinct OpenAI event ID per sample.

The batch.completed, response.completed, and realtime.call.incoming samples all reuse evt_685343a1381c819085d44c354e1b330e. OpenAI event objects use id as the unique event identifier, so consumers using this as their dedupe key can treat distinct samples as the same event.

internal-packages/webhook-sources/src/handAuthored/elevenlabs.ts-18-91 (1)

18-91: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Include the audio availability fields in the transcription samples.

Both post_call_transcription examples omit has_audio, has_user_audio, and Has_response_audio, which are part of the ElevenLabs post-call webhook data object. Add realistic boolean values so the catalog samples match current payload shape.

Also applies to: 103-184

internal-packages/webhook-sources/src/handAuthored/linear.ts-19-21 (1)

19-21: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Update the stale webhookTimestamp values.

The millisecond timestamps resolve to July 2025 while the adjacent createdAt values are July 2026. This gives consumers contradictory event times.

Proposed fix

-      webhookTimestamp: 1751380338084,
+      webhookTimestamp: 1782916338084,
...
-      webhookTimestamp: 1751388322391,
+      webhookTimestamp: 1782924322391,
...
-      webhookTimestamp: 1751389329514,
+      webhookTimestamp: 1782925329514,
...
-      webhookTimestamp: 1751361344201,
+      webhookTimestamp: 1782897344201,
...
-      webhookTimestamp: 1751389533802,
+      webhookTimestamp: 1782925533802,

Also applies to: 63-65, 121-124, 138-140, 173-175

internal-packages/webhook-sources/src/roundtrip.test.ts-61-64 (1)

61-64: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Fail when a selected sample has no verifier config.

A sample with presetId: "custom" or a stale provider mapping enters verifiableSamples, then passes without signing or verification because Line 64 returns. Throw instead so the catalog cannot silently lose round-trip coverage.

Proposed fix

       const config = configForSample(sample);
-      if (!config) return;
+      if (!config) {
+        throw new Error(`No verifier config for ${sample.provider} / ${sample.eventType}`);
+      }

internal-packages/webhook-sources/src/handAuthored/close-crm.ts-222-238 (1)

222-238: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Keep the event and payload opportunity IDs consistent.

Line 223 and Line 238 describe different opportunities, so filters based on event.object_id disagree with task code reading event.data.id.

Proposed fix

-          id: "oppo_8H4sjNso7FyBFaeR3RXi5PMJbilfo0c6UPCxsJtEhCO",
+          id: "oppo_7H4sjNso7FyBFaeR3RXi5PMJbilfo0c6UPCxsJtEhCO",

internal-packages/webhook-sources/src/registry/index.ts-65-67 (1)

65-67: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Guard the registry lookup to own keys only.

registry is a normal object, so getProvider("toString") or getProvider("__proto__") returns an inherited value despite the ProviderRegistryEntry | undefined return type. Update the generator to use an own-key check or a null-prototype map.

apps/webapp/app/services/webhookDeliveriesReplicationInstance.server.ts-15-16 (1)

15-16: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Use env.DATABASE_URL instead of reading process.env directly.

DATABASE_URL is already exposed by app/env.server.ts, and this function already uses env for every other variable. Replace the raw const { DATABASE_URL } = process.env read with env.DATABASE_URL.

Source: Path instructions

apps/webapp/app/presenters/v3/WebhookDeliveryDetailPresenter.server.ts-87-90 (1)

87-90: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Use findFirst instead of findUnique.

-        this.replica.sessionRun.findUnique({
+        this.replica.sessionRun.findFirst({
           where: { runId: delivery.runId },
           select: { session: { select: { friendlyId: true, externalId: true } } },
         }),

As per path instructions: "Always use Prisma findFirst instead of findUnique."

Source: Path instructions

apps/webapp/app/presenters/v3/ApiWebhookDeliveryPresenter.server.ts-62-67 (1)

62-67: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Error message omits a valid status value.

The "Allowed" list in the validation error hardcodes pending, processing, succeeded, failed but omits filtered, even though filtered is a valid key in API_STATUS_TO_DB and will be accepted. This misleads API consumers debugging an invalid filter[status] value.

🐛 Proposed fix

-          message: `Invalid status values: ${invalid.join(
-            ", "
-          )}. Allowed: pending, processing, succeeded, failed.`,
+          message: `Invalid status values: ${invalid.join(
+            ", "
+          )}. Allowed: ${Object.keys(API_STATUS_TO_DB).join(", ")}.`,

apps/webapp/app/components/webhookDeliveries/v1/WebhookDeliveryFilters.tsx-39-44 (1)

39-44: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Status filter is missing the FILTERED option.

deliveryStatuses only covers 4 of the 5 WebhookDeliveryStatus values. The delivery timeline builder (and this PR's own test suite) treats FILTERED as a first-class outcome, and the server-side loader already accepts it via Object.values(WebhookDeliveryStatus) — but this dropdown has no way to select it, so users can't filter deliveries down to filtered-out events through the UI.

 const deliveryStatuses: { value: WebhookDeliveryStatus; title: string; color: string }[] = [
   { value: "PENDING", title: "Pending", color: "`#878C99`" },
   { value: "PROCESSING", title: "Processing", color: "`#3B82F6`" },
   { value: "SUCCEEDED", title: "Succeeded", color: "`#28BF5C`" },
   { value: "FAILED", title: "Failed", color: "`#E11D48`" },
+  { value: "FILTERED", title: "Filtered", color: "`#878C99`" },
 ];

Since the comment says this list intentionally "Match[es] DeliveriesTable's DELIVERY_STATUS_COLOR / DELIVERY_STATUS_LABEL," worth checking whether that file (not in this batch) also needs the same addition.

apps/webapp/app/components/webhookDeliveries/v1/DeliveriesTable.tsx-240-247 (1)

240-247: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

"View session" popover item uses the run color, not the session color.

Elsewhere in this file (Line 160-161) sessions use text-sessions; this menu item uses text-runs for "View session", inconsistent with the established color-coding convention distinguishing sessions from runs.

🎨 Fix

           {sessionPath ? (
             <PopoverMenuItem
               to={sessionPath}
               icon={ArrowRightIcon}
-              leadingIconClassName="text-runs"
+              leadingIconClassName="text-sessions"
               title="View session"
             />
           ) : null}

apps/webapp/app/components/webhookConsole/SampleSourcePicker.tsx-56-62 (1)

56-62: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Category search is case-sensitive; label search isn't.

query is lowercased but p.category is compared as-is, so a category like "Payments" won't match a lowercase search term even though the label check does lowercase.

🐛 Fix

-      (p) => p.label.toLowerCase().includes(query) || (p.category ?? "").includes(query)
+      (p) => p.label.toLowerCase().includes(query) || (p.category ?? "").toLowerCase().includes(query)

packages/core/src/v3/schemas/schemas.ts-2-8 (1)

2-8: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Restore type-only imports for RequireKeys, AnyRunTypes, and the inferred RetrieveRunResponse.

These symbols are export type utilities/inferences, not runtime exports; importing them without type can break with isolatedModules/verbatimModuleSyntax-style builds that cannot drop unused imports.

• packages/core/src/v3/schemas/schemas.ts#L2-L8
• packages/core/src/v3/types/index.ts#L1-L3

packages/core/src/v3/schemas/webhookApi.ts-64-70 (1)

64-70: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

pagination is required here but documented as optional (Line 7). A deliveries response serialized as { data } (no pagination key) would fail ListWebhookDeliveriesResponse.parse(...). Consider making it optional to match the documented { data, pagination? } contract and avoid a parse failure.

🛡️ Proposed change

 export const ListWebhookDeliveriesResponse = z.object({
   data: z.array(WebhookDeliveryListItem),
   pagination: z.object({
     next: z.string().optional(),
     previous: z.string().optional(),
-  }),
+  }).optional(),
 });

internal-packages/webhook-engine/src/engine/verification/urlSecret.ts-9-17 (1)

9-17: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Unguarded new URL(input.url) can throw on malformed input.

If input.url isn't a valid absolute URL, new URL() throws synchronously and isn't caught here or (per the cross-file engine/index.ts ingest() evidence) by the caller, risking an unhandled 5xx instead of a fail-closed { ok: false } result — the same fail-closed contract violated in verification/index.ts.

🛡️ Proposed fix

   verify(config, input): VerifierResult {
     const cfg = config as Extract<UrlSecretConfig, { scheme: "url-secret" }>;
-    const u = new URL(input.url);
+    let u: URL;
+    try {
+      u = new URL(input.url);
+    } catch {
+      return { ok: false, error: "invalid url", idempotencyKey: derive0(cfg, input) };
+    }

internal-packages/replication/src/client.ts (1)

34-39: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use a type alias for this configuration shape.

LogicalReplicationClientOptions is a data shape, so extend a type alias rather than an interface.

Proposed change

-export interface LogicalReplicationClientOptions {
+export type LogicalReplicationClientOptions = {
   // ...
-}
+};

Source: Coding guidelines

internal-packages/webhook-sources/catalog/providers.json (1)

23-923: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Catalog omits 11 registry providers that exist in code.

registry/adyen.ts, bigcommerce.ts, bitbucket.ts, checkout.ts, commercelayer.ts, monday.ts, paddlebilling.ts, paddleclassic.ts, paypal.ts, pipedrive.ts, and woocommerce.ts all exist per the cohort's file list, but none of them have a corresponding entry in this providers array. catalog/status.ts derives "remaining"/"claimable"/"complete" counts purely from this file, so these 11 providers are silently excluded from progress tracking (the tool will report the wave as fully done while 11 shipped providers are untracked).

internal-packages/webhook-sources/src/handAuthored/slack.ts (1)

17-17: 🔒 Security & Privacy | 🔵 Trivial | 💤 Low value

Replace the credential-shaped Slack token with an explicit fixture value.

The shared-secret callback token is repeated in several payloads; use an unmistakable placeholder such as "fixture-token" across these samples.

Sources: MCP tools, Linters/SAST tools

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.test.tasks.$taskParam/route.tsx (1)

134-138: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use v3WebhookTaskPath instead of a hand-built URL.

This PR adds v3WebhookTaskPath in pathBuilder.ts (which also encodeURIComponents the slug); this redirect duplicates that logic with raw string interpolation instead. See consolidated comment.

apps/webapp/app/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.webhooks.endpoints.$endpointParam.send.ts (1)

175-176: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Use v3WebhookDeliveryPath instead of a hand-built URL.

Duplicates the new v3WebhookDeliveryPath pathBuilder helper with raw string interpolation. See consolidated comment.

apps/webapp/app/components/webhookConsole/WebhookComposer.tsx (1)

117-119: 🎯 Functional Correctness | 🔵 Trivial | 💤 Low value

signatureMode is not reconciled when the selected endpoint changes.

signatureMode is initialized once from signedAvailable. When the user switches endpoints (dropdown at Lines 267-287) to one that is asymmetric or has no signing secret, a previously-selected "signed" mode stays set even though its SelectItem becomes disabled, so a subsequent send submits signed for an unsupported endpoint. Consider resetting to "simulate" in an effect when signedAvailable becomes false.

apps/webapp/app/v3/services/createBackgroundWorker.server.ts (1)

225-232: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Non-ServiceValidationError webhook-sync failures are swallowed (deploy reports success).

Unlike syncDeclarativeSchedules above (which wraps unexpected errors into a ServiceValidationError and rethrows), a transient failure here (e.g. a webhookPrisma/prisma error) is only logged; the deploy then completes as successful with webhook endpoints left unsynced/partially updated. Consider mirroring the schedules path so an infra failure fails the deploy rather than silently diverging routing state.

apps/webapp/app/presenters/v3/WebhookDetailPresenter.server.ts (1)

447-450: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Prefer the structured logger over console.error (also at Line 541).

console.error bypasses Logger.onError forwarding (e.g. Sentry) and structured fields used elsewhere in the presenters. Consider importing logger from ~/services/logger.server for these ClickHouse query-failure paths.

apps/webapp/app/presenters/v3/ApiWebhookDeliveryPresenter.server.ts (1)

32-42: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Duplicate delivery-mapping logic.

ApiWebhookDeliveryPresenter.call re-implements the same field mapping already encapsulated in toApiListItem, risking silent drift if one is updated without the other.

♻️ Proposed refactor

       return {
-        id: d.friendlyId,
-        webhook: d.webhook?.slug ?? null,
-        status: DB_STATUS_TO_API[d.status],
-        externalDeliveryId: d.externalDeliveryId,
-        runId: d.run?.friendlyId ?? null,
-        createdAt: d.createdAt,
-        processedAt: d.processedAt,
+        ...toApiListItem(d),
         idempotencyKey: d.idempotencyKey,
         event: d.parsedEvent ?? null,
         headers: (d.headers as Record<string, string> | null) ?? null,
         rawBodyHash: d.rawBodyHash,
         error: d.errorMessage,
         filterReason: d.filterReason,
         updatedAt: d.updatedAt,
       };

Note: toApiListItem takes WebhookDeliveryListItem; d here is a WebhookDeliveryDetail — confirm it's structurally compatible (a superset) before applying.

Also applies to: 133-148

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.webhooks.deliveries.$deliveryParam/route.tsx (1)

109-115: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Duplicate duration-formatting logic.

This local formatDuration re-implements what formatDuration from @trigger.dev/core/v3/utils/durations already provides (used in apps/webapp/app/components/webhookDeliveries/v1/DeliveryTimeline.tsx). Consider reusing the shared utility for consistent formatting across the delivery UI.

internal-packages/webhook-engine/src/engine/types.ts (1)

28-58: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Prefer a type alias for the WebhookEngineOptions data shape.

WebhookEngineOptions is a plain configuration/object shape, so the repo convention of types-over-interfaces applies (the two callback interfaces are behavioral contracts and are fine as-is).

♻️ Convert to a type alias

-export interface WebhookEngineOptions {
+export type WebhookEngineOptions = {
   logger?: Logger;
   ...
   deliverToSession?: DeliverWebhookToSessionCallback;
-}
+};

As per coding guidelines: "Use types over interfaces for TypeScript".

Sources: Coding guidelines, Learnings

internal-packages/webhook-engine/src/engine/index.ts (1)

70-93: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Remove the redundant /milliseconds suffix from the duration metric.

The histogram is declared with unit: "ms" and Prometheus-exported metric names already receive the _milliseconds unit suffix, so these records are exported as webhook_delivery_execution_duration_milliseconds_milliseconds. Rename it to webhook_delivery_execution_duration and keep the "ms" unit; update dashboards/queries accordingly.

Source: Coding guidelines

internal-packages/webhook-engine/src/engine/verification/sharedSecret.ts (1)

25-48: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Loosely-typed cfg: any in extractCandidate/failSS.

Unlike hmac.ts's fail(error, cfg: HmacConfig, input), these helpers type cfg as any, losing compile-time checks on cfg.placement, cfg.fieldName, and cfg.idempotencyField in secret-extraction code.

♻️ Proposed fix: use the narrowed config type

-function extractCandidate(cfg: any, input: VerifyInput): string | undefined {
+function extractCandidate(
+  cfg: Extract<SharedSecretConfig, { scheme: "shared-secret" }>,
+  input: VerifyInput
+): string | undefined {

-function failSS(error: string, cfg: any, input: VerifyInput): VerifierResult {
+function failSS(
+  error: string,
+  cfg: Extract<SharedSecretConfig, { scheme: "shared-secret" }>,
+  input: VerifyInput
+): VerifierResult {

Also applies to: 50-62